﻿//-----------------------------------------------------------------------------
// <copyright file="IOpenFileDialog.cs" company="William E. Kempf">
//     Copyright (c) William E. Kempf.
// </copyright>
//-----------------------------------------------------------------------------

namespace Onyx.Windows
{
    using System.Diagnostics.CodeAnalysis;
    using System.IO;

    /// <summary>
    /// Defines a generalized OpenFileDialog.
    /// </summary>
    public interface IOpenFileDialog : IFileDialog
    {
        /// <summary>
        /// Gets or sets a value indicating whether <see cref="IOpenFileDialog"/>
        /// allows users to select multiple files.
        /// </summary>
        /// <value><see langword="true"/> if multiple selections are allowed; otherwise,
        /// <see langword="false"/>. The default value is <see langword="false"/>.</value>
        [SuppressMessage("Microsoft.Naming",
            "CA1704:IdentifiersShouldBeSpelledCorrectly",
            MessageId = "Multiselect",
            Justification = "We're matching the BCL class.")]
        bool Multiselect { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether the read-only check box displayed
        /// by <see cref="IOpenFileDialog"/> is selected.
        /// </summary>
        /// <value><see langword="true"/> if the checkbox is selected; otherwise, <see langword="false"/>.
        /// The default value is <see langword="false"/>.</value>
        bool ReadOnlyChecked { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether <see cref="IOpenFileDialog"/>
        /// contains a read-only check box.
        /// </summary>
        /// <value><see langword="true"/> if the checkbox is displayed; otherwise, <see langword="false"/>.
        /// The default value is <see langword="false"/>.</value>
        bool ShowReadOnly { get; set; }

        /// <summary>
        /// Opens a read-only stream for the file that is selected by the user using
        /// <see cref="IOpenFileDialog"/>.
        /// </summary>
        /// <returns>A new <see cref="System.IO.Stream"/> that contains the selected
        /// file.</returns>
        /// <exception cref="System.InvalidOperationException">No files were selected
        /// in the dialog.</exception>
        /// <remarks>The file is opened with read-only permission
        /// (<see cref="System.IO.FileMode.Open"/>, <see cref="System.IO.FileAccess.Read"/>,
        /// and <see cref="System.IO.FileShare.Read"/>), whether or not the Read Only
        /// checkbox is checked in the dialog. Because the file is opened without the
        /// ability to overwrite or write to the file, an application can safely load
        /// a file while executing within partial trust restrictions.</remarks>
        Stream OpenFile();

        /// <summary>
        /// Creates an array that contains one read-only stream for each file selected
        /// by the user using <see cref="IOpenFileDialog"/>.
        /// </summary>
        /// <returns>An array of multiple new <see cref="System.IO.Stream"/> objects
        /// that contain the selected files.</returns>
        /// <exception cref="System.InvalidOperationException">No files were selected
        /// in the dialog.</exception>
        /// <remarks>Each file is opened with read-only permission
        /// (<see cref="System.IO.FileMode.Open"/>, <see cref="System.IO.FileAccess.Read"/>,
        /// and <see cref="System.IO.FileShare.Read"/>), whether or not the Read Only
        /// checkbox is checked in the dialog. Because each file is opened without
        /// the ability to overwrite or write to the file, an application can safely
        /// load one or more files while executing within partial trust restrictions.</remarks>
        Stream[] OpenFiles();
    }
}
